### User input

When your program is invoked, user usually gives it some input in form of options (some of them with
arguments attached) and simple arguments.

Here, I will explain how CLAP interprets, analyzes and processes user input before it expose it to
you in form that is easy to work with.


----

&nbsp;

#### Structure of input

Whole input is contained in `argv` variable but is logically divided into
two main sections: *input* and *operands*.
As of version 0.7.1 they are not really split during input analysis but there is a special method
`_getinput()` which will extract only the *input* part of argv.

General structure is shown below (`foo` is the name of example program):

```
foo [options [option-arguments]]... [--] [arguments]...
```

##### *input*

This part consists of options (switches) and their arguments. It's finished when CLAP encounters a *breaker*
(special two-hyphen string (`--`) meaning: terminate input analyzing HERE because from now on 
only arguments will follow), or a *non-option* and *non-option-argument* string.
Only this part is checked for mistakes since arguments are too program-specific and CLAP leaves
their validation to users.

##### *operands*

Everything that follows first *non-option* and *non-option-argument* string or *breaker*.


----

&nbsp;

#### Input items types

CLAP divides user input into three types:

*   *options* (or *switches*),
*   *option-arguments*,
*   *operands*.


----

&nbsp;

##### 1. Options (switches)

Options are strings that hold special meaning defined by the programmer or creator of UI.
They can (but doesn't have to) request fixed-length lists of arguments of different types to be
passed to them.

Options are recognized using regular expressions (see the code in `clap/base.py` to check the exact
regexp used) and there are two types of them with the same functionality but with different rules for
appearance:

*   *short* options:    one-character preceded by single hyphen, e.g. `-o`,
*   *long* options:     two or more characters preceded by two hyphens, e.g. `--output`,

----

##### 1.1 Short options

Short options are one-character switches. Usually they have long aliases which are more descriptive but
entering just one character saves keystrokes.

Short option is a string starting with single hyphen (`-`) immediately followed by a single letter or
number (the *name* of the short option).
Name cannot be another hyphen - two hyphens (`--`) are special string used to tell a program that it's
input is finished and from now on only non-option arguments will follow.

##### Abbreviations

>   **Note to programmers**: if you want to enable your users to use abbreviations you must first format
>   the input using `Formatter()` object (`clap.formater.Formatter()`) because parser is not able to understand
>   them.

Short options are useful for users who memorized some part of the program's interface as they can be
passed in abbreviated form. This means that such input:

    foo -a -b -c -d

can be abbreviated to:

    foo -abcd

and will still hold the same functionality.

However, when a short option requests some argument it is not possible to connect it with others unless
it's the last one. This means that input showed below:

    foo -a -b -c spam -d

cannot be abbreviated to input of such form (it would even raise an exception):

    foo -abcd spam

but can be abbreviated to:

    foo -abdc spam


----

##### 1.2 Long options

Long options are two-or-more character switches. Their names can contain hyphens, letters and numbers.

Long options are more descriptive but they lack the abbreviation feature of short options.


----

&nbsp;

##### 2. Option-arguments

These are non-option strings which can be mixed with options and won't terminate input parsing.
List of arguments for an option is a list of callback functions taking one argument. 

Example: option `--point` requires two float arguments (X and Y axis) it should be defined as:

    parser.add(short='p', long='point', arguments=[float, float])

    #   some code

    x, y = parser.get('--point')

Multiple arguments are returned as tuples, single as single objects.


##### Callback functions

You can pass *any* single-argument function as a type but keep in mind that there are few rules:

*   user must supply valid value for it,
*   on invalid data it should raise `ValueError` or return default value,

It's safe to use basic types: `str`, `int` and `float`. 

There is no way to turn off the conversion - if you want general type option and
decide later what to do with it use `str` type as it won't get converted in any way (only conversion
will be from string to string).


##### Variable-length arguments list

Currently there is no way to define a variable-length list of arguments.

##### Optional arguments

Optional arguments are not yet implemented. There is no fixed time when they'll be.
